.\" This file is generated automatically by convert.pl from htags/manual.in.
.TH HTAGS 1 "July 2010" "GNU Project"
.SH NAME
htags \- generate a hypertext from a set of source files.
.SH SYNOPSIS
\fBhtags\fP [-acDfFghInosTvwx][-d \fIdbpath\fP][-m \fIname\fP][-t \fItitle\fP][\fIdir\fP]
.br
.SH DESCRIPTION
\fBHtags\fP generates a hypertext from a set of source files of
C, C++, Yacc, Java, PHP and Assembly.
.PP
In advance of using this command, you should execute \fBgtags\fP(1)
in the root directory of a source project.
Then you can execute \fBhtags\fP in the same place.
\fBHtags\fP makes a directory named \'HTML\', and puts a hypertext in it.
You can start browsing at \'HTML/index.html\'.
.PP
Since \fBhtags\fP generates a static hypertext as long as the \fB-D\fP or \fB-f\fP
option is not specified, you can move it anywhere and browse it by any browser without
any HTTP server.
.PP
This command has so many options.
If you are new on \fBhtags\fP, it is recommended to use the \fB--suggest\fP option.
With that option, \fBhtags\fP chooses popular options on behalf of you.
.SH OPTIONS
The following options are available:
.TP
\fB-a\fP, \fB--alphabet\fP
Make an alphabetical object index which is suitable for large projects.
.TP
\fB--auto-completion\fP[=\fIlimit\fP]
Enable auto completion facility for the input form.
If \fIlimit\fP is specified, the number of candidates is limited to the value.
Please note that this function requires javascript language in your browser.
.TP
\fB--caution\fP
Display a caution message on the top page.
.TP
\fB--cflow\fP \fIcflowfile\fP
Add a call tree by \fBcflow\fP(1). \fIcflowfile\fP must be posix format.
If you use GNU cflow, invoke the command at the project root directory
with the \fB--format=posix\fP option.
This option is deprecated. Please use the \fB--call-tree\fP or
\fB--callee-tree\fP instead.
.TP
\fB--call-tree\fP \fIcallfile\fP
Add a call tree by \fBcflow\fP(1). \fIcallfile\fP must be posix format.
If you use GNU cflow, invoke the command at the project root directory
with the \fB--format=posix\fP option.
.TP
\fB--callee-tree\fP \fIcalleefile\fP
Add a callee tree by \fBcflow\fP(1). \fIcalleefile\fP must be posix format.
If you use GNU cflow, invoke the command at the project root directory
with the \fB--format=posix\fP and \fB--reverse\fP option.
.TP
\fB-c\fP, \fB--compact\fP
Compress html files by \fBgzip\fP(1).
You need to configure HTTP server so that \fBgzip\fP(1)
is invoked for each compressed file.
See \'HTML/.htaccess\' that is generated by htags.
.TP
\fB--cvsweb\fP \fIurl\fP
Add a link to cvsweb. \fIurl\fP is used as the base of URL.
When directory \'CVS\' exists in the root directory of the source project,
the content of \'CVS/Repository\' is used as the relative path from the base.
.TP
\fB--cvsweb-cvsroot\fP \fIcvsroot\fP
Specify cvsroot in cvsweb URL.
.TP
\fB-D\fP, \fB--dynamic\fP
Generate object lists dynamically using CGI program.
Though this option decrease both the size and generation time of hypertext,
you need to start up HTTP server.
.TP
\fB-d\fP, \fB--dbpath\fP \fIdbpath\fP
Specify a directory in which \'GTAGS\' exist.
The default is the current directory.
.TP
\fB--disable-grep\fP
Disable grep in the search form(-f,--form).
.TP
\fB--disable-idutils\fP
Disable idutils in the search form(-f,--form).
.TP
\fB-F\fP, \fB--frame\fP
Use frames for the top page.
.TP
\fB-f\fP, \fB--form\fP
Add a search form using CGI program.
You need to start up HTTP server for it.
.TP
\fB--fixed-guide\fP
Put a fixed guide at the bottom of the source code.
.TP
\fB--full-path\fP
Use full path name in the file index.
By default, use just the last component of a path.
.TP
\fB-g\fP, \fB--gtags\fP
Execute \fBgtags\fP(1) before starting job.
The \fB-v\fP, \fB-w\fP and \fIdbpath\fP options are passed to \fBgtags\fP.
.TP
\fB--gtagsconf\fP \fIfile\fP
Set the \fBGTAGSCONF\fP environment variable to \fIfile\fP.
.TP
\fB--gtagslabel\fP \fIlabel\fP
Set the \fBGTAGSLABEL\fP environment variable to \fIlabel\fP.
.TP
\fB-h\fP, \fB--func-header\fP[=\fIposition\fP]
Insert function header for each function.
By default, \fBhtags\fP doesn't generate it.
You can specify the position using \fIposition\fP argument,
which allows one of \fIbefore\fP, \fIright\fP and \fIafter\fP.
The default position is \fIafter\fP.
.TP
\fB--html\fP
Generate HTML hypertext instead of XHTML.
.TP
\fB--html-header\fP \fIfile\fP
Insert header records derived from \fIfile\fP into the HTML header.
.TP
\fB-I\fP, \fB--icon\fP
Use icons instead of text for some links.
.TP
\fB--insert-footer\fP \fIfile\fP
Insert custom footer derived from \fIfile\fP before </body> tag.
.TP
\fB--insert-header\fP \fIfile\fP
Insert custom header derived from \fIfile\fP after <body> tag.
.TP
\fB--item-order\fP \fIspec\fP
Specify the order of the items in the top page.
The \fIspec\fP is a string consisting of item signs in order.
Each sign means as follows:
\fBc\fP: caution; \fBs\fP: search form;
\fBm\fP: mains; \fBd\fP: definition; \fBf\fP: files; \fBt\fP: call tree.
The default is \fIcsmdf\fP.
.TP
\fB-m\fP, \fB--main-func\fP \fIname\fP
Specify startup function name. The default is \fImain\fP.
.TP
\fB-n\fP, \fB--line-number\fP[=\fIcolumns\fP]
Print line numbers. By default, doesn't print line numbers.
The default value of \fIcolumns\fP is 4.
.TP
\fB--map-file\fP
Generate files \'MAP\'.
.TP
\fB-o\fP, \fB--other\fP
Pick up not only source files but also other files in the file index.
.TP
\fB--overwrite-key\fP
Allow the same key as the parameter of the \fB--system-cgi\fP option.
.TP
\fB--system-cgi\fP \fIkey\fP
Use the system CGI script. The \fIkey\fP must be a unique key in your site.
At the first time, you should (1) copy the CGI script written by this command
into the system CGI directory, and (2) execute bless.sh script at the HTML directory
as a root user.
.TP
\fB-s\fP, \fB--symbol\fP
Make anchors not only for object definitions and references but also other symbols.
.TP
\fB--show-position\fP
Show position per function definition. The default is false.
.TP
\fB--statistics\fP
Print statistics information.
.TP
\fB--suggest\fP
\fBHtags\fP chooses popular options on behalf of beginners.
It is equivalent to '-aghInosTxv --show-position --fixed-guide' now.
.TP
\fB--suggest2\fP
\fBHtags\fP chooses popular options on behalf of beginners.
This option enables frame, AJAX and CGI facility in addition
to the facilities by the \fB--suggest\fP option.
.TP
\fB-T\fP, \fB--table-flist\fP[=\fIrows\fP]
Use <table> tag to display the file index.
You can optionally specify the number of rows. The default is 5.
.TP
\fB-t\fP, \fB--title\fP \fItitle\fP
Title of the hypertext.
The default is the last component of the path of the current directory.
.TP
\fB--table-list\fP
Use <table> tag to display the tag list.
.TP
\fB--tree-view\fP[=\fItype\fP]
Use treeview for the file index.
Please note that this function requires javascript language in your browser.
.TP
\fB-v\fP, \fB--verbose\fP
Verbose mode.
.TP
\fB-w\fP, \fB--warning\fP
Print warning messages.
.TP
\fB-x\fP, \fB--xhtml\fP[=\fIversion\fP]
Generate XHTML hypertext. This is the default.
If the \fB--frame\fP option is specified then
generate XHTML-1.0 Frameset for index.html
and generate XHTML-1.0 Transitional for other files,
else if \fIversion\fP is 1\.1 or config variable
xhtml_version is set to 1\.1 then generate
XHTML-1.1 else XHTML 1.0 Transitional.
.TP
\fIdir\fP
The directory in which the result of this command is stored.
The default is the current directory.
.SH EXAMPLES
.nf
$ gtags -v
$ htags -sanohITvt 'Welcome to XXX source tour!'
$ firefox HTML/index.html
.PP
$ htags --suggest
.fi
.SH FILES
.TP
\'GTAGS\'
Tag file for object definitions.
.TP
\'GRTAGS\'
Tag file for object references.
.TP
\'GPATH\'
Tag file for files.
.TP
\'$HOME/.globalrc\', \'/etc/gtags.conf\', \'[sysconfdir]/gtags.conf\'
Configuration files.
.TP
\'HTML/index.html\'
Startup file.
.TP
\'HTML/MAP\'
Mapping file for converting tag name into the path of tag list.
.TP
\'HTML/FILEMAP\'
Mapping file for converting file name into the path of the file.
.TP
\'HTML/style.css\'
Style sheet file. This file is generated when the \fB--xhtml\fP
option is specified.
.TP
\'HTML/.htaccess\'
Local configuration file for Apache. This file is generated when
the \fB-f\fP, \fB-D\fP or \fB-c\fP option is specified.
.TP
\'HTML/GTAGSROOT\'
If this file exists, CGI program \'global.cgi\' sets
environment variable GTAGSROOT to the contents of it.
If you move directory \'HTML\' from the original place,
please make this file.
.SH ENVIRONMENT
The following environment variables affect the execution of \fBhtags\fP:
.TP
\fBTMPDIR\fP
The location used to stored temporary files. The default is \'/tmp\'.
.TP
\fBGTAGSCONF\fP
Configuration file. The default is \'$HOME/.globalrc\'.
.TP
\fBGTAGSLABEL\fP
Configuration label. The default is \fIdefault\fP.
.TP
\fBGTAGSCACHE\fP
The size of B-tree cache. The default is 50000000 (bytes).
.TP
\fBGTAGSFORCECPP\fP
If this variable is set, each file whose suffix is 'h' is treated
as a C++ source file.
.SH CONFIGURATION
The following configuration variables affect the execution of \fBhtags\fP:
If the \fB--xhtml\fP option is specified then all definitions of
HTML tag are ignored.
Instead, you can customize the appearance using style sheet file
(\'style.css\').
.TP
datadir(string)
Shared data directory. The default is '/usr/local/share' but
you can change the value using configure script.
\fBHtags\fP look up template files in the 'gtags' directory
in this data directory.
.TP
gzipped_suffix(string)
Suffix for compressed html file. The default is 'ghtml'.
.TP
htags_options(string)
Default options for \fBhtags\fP. This value is inserted into
the head of arguments.
.TP
include_file_suffixes(comma separated list)
Suffixes of include files. The default is 'h,hh,hxx,hpp,H,inc.php'.
.TP
langmap(comma separated list)
Language mapping. Each comma-separated map consists of
the language name, a colon, and a list of file extensions.
Default mapping is 'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.
.TP
ncol(number)
Columns of line number. The default is 4.
.TP
normal_suffix(string)
Suffix for normal html file. The default is 'html'.
.TP
script_alias(string)
Script alias for system cgi script (\fB--system-cgi\fP).
.TP
tabs(number)
Tab stop. The default is 8.
.TP
xhtml_version(1.0|1.1)
XHTML version. 1.0 and 1.1 are acceptable. The default is 1.0.
.SH DIAGNOSTICS
\fBHtags\fP exits with a non 0 value if an error occurred, 0 otherwise.
.SH "SEE ALSO"
\fBglobal\fP(1),
\fBgtags\fP(1).
.PP
GNU GLOBAL source code tag system
.br
(http://www.gnu.org/software/global/).
.SH BUG
Generated hypertext is VERY LARGE.
In advance, check the space of your disk.
.PP
PHP support is far from complete.
.PP
The -f, -D or -c option generates CGI programs.
If you open the result to the public, please recognize the security dangers.
.SH AUTHOR
Shigio YAMAGUCHI, Hideki IWAMOTO and others.
.SH HISTORY
The \fBhtags\fP command appeared in FreeBSD 2.2.2.
